17 Bit Software 3: The Continuation/17-Bit_The_Continuation_Disc.iso/amigan/amigan 11/gomf/gomf.readmeoryou'llguru!!

Text File | 1994-01-27 | 15.2 KB | 303 lines

                                    GOMF1.0
                                    ~~~~~~~
  Introduction
  ~~~~~~~~~~~~

  Please read the entire text of this file before using GOMF1.0.  It contains
  important information and could save you a lot of hassle.

  The name of this application is an acronym for 'Get Outa My Face'.  I've
  found myself mumbling this phrase all too often when public domain or even
  commercial programs have created errors, bringing on the ubiquitous guru
  meditation alert.  Of course the majority of these system traps I've seen
  were caused by address errors in my own code, while in the early stages of
  writing and debugging my own software.

  It is true that the user has the option, at the system requester presented
  before the alert, of simply ignoring it and continuing to run programs,
  even though the system is somewhat crippled.  I, however, found this to be
  almost as inconvenient as rebooting.  I did so only when I had to save
  valuable data to disk or was anticipating another problem with the program
  I was developing.  At times I would run my program, select an option,
  crash, make notes, click the system requester to the rear, run the program
  again, select another option, crash, and make more notes, in a loop until I
  had all the information I could glean.  Then I'd click a system requester
  back to the front and go through the guru meditation every Amiga user has
  been forced into.  There had to be a better way!

  Apparently in the nuclear power generation industry when the operating
  system senses a grevious enough malfunction it shuts itself down.  The
  operators or technicians then say that the 'system scrammed'.  I think this
  is an appropriate way of describing the Amiga user's perdicament.

  My first experiments with the system traps was to write an error handler
  module, which is linked to the assembler code I'm developing, that allows
  me to clean up and debug while never crashing at all.  This worked rather
  well because the program that caused the error 'knew' itself intimately and
  could therefore extricate itself, upon user direction to do so, from the
  system, with no ill effects.  I should mention at this point that the kind
  of crashes I'm talking about are only those that cause a requester, not the
  ones that have the system so badly out of shape that the normal interface
  is gone.  The link module would protect system integrity only from its own
  errors.  This meant that, if some other utility I was using caused an
  error, then the guru would come with the handbasket.

  The second version of GOMF1.0 was designed to provide its error handling
  features globally within the system.  It would then respond to errors in
  any task or process.  The error handler would know nothing about a program,
  except what it could fetch out of the system structures.  This means that
  GOMF1.0 can only remove public memory, including, the task or process, its
  memory allocations, messages unanswered and display screens and windows,
  from the system.  This works well.  It may be that there is one more opener
  than closer left in a library, device or resource, but this dosen't impede
  normal operations like the guru alert is wont to do.  Any memory allocated
  and maintained in a private memory list or messages saved internally by a
  program, cannot be released to the system.

  The benifits of the GOMF1.0 system make it worth using, I believe, even for
  the casual user.  The most obvious reason is the reduction in the frequency
  of having to reboot the system at the guru meditation prompt.  This will
  save you time.  When you don't have to reboot, you don't have to wait while
  your startup-sequence configures your machine.  I've found this a real boon
  because I was reticent to have a lot of background tasks or utilities
  activated, mainly because I'd have to wait for them to be set up each time
  I was forced to reboot.  When using GOMF1.0 this is reduced to the minimum
  possible, I believe.

  If you don't have to reset the Amiga, you lose no data, unless the creator
  of the error has trashed your workspace.  This saves your work.  You have
  the option of saving out to disk any important files.  I suggest doing this
  to temporary disk files so that if the data is corrupted, you have a chance
  to verify this before overwriting your originals.  A recoverable ram disk,
  otherwise known as VD0:, also protects contents of ram from losses caused
  by resets.  They can be mounted upon rebooting to recover their previous
  contents.  They will not protect against data corruption caused by a
  runaway program either, however.  The main difference between GOMF1.0 and a
  recoverable ram disk, to a user or programmer, is the same as the main
  difference between VD0: and RAM:, other than recoverability.  Floppy disk
  is reasonably fast.  RAM: is very fast.  VD0: is somewhere in between.
  From the standpoint of speed, GOMF1.0 and RAM: are preferable to VD0:.  'I
  feel the need....the need for speed!'

  I can hear some of you devious (intelligent?) computerists out there
  thinking... 'Why not use RAM: for speed, when disk intensive operations
  are called for, and place all important data in VD0: files so that they can
  be recovered if a reset is necessary, just in case GOMF1.0 is unable to
  recover from the crash?'  You know, I'm glad you thought of that.  It works
  well.  GOMF1.0, RAM: and VD0: are foundational tools for programming, at
  least in the early stages.  Development is quicker and more reliable.


  Policies
  ~~~~~~~~

  On all software described herein, I express no warranty of, but not
  limited to, the usefulness, method of operation, or the user's
  satisfaction with the results.  Neither do I imply such a warranty.  You
  signify your willingness to exempt me from all responsibility for the
  results of the use of these software products by your use of them.

  The GOMF1.0 software, listed below, may be shared with anyone, provided
  this is done for no profit, other than a nominal fee for disk copying.  I
  require also that all files listed be kept together as found.  I wish none
  of this text file nor any of the executable programs be altered in any way.
  GOMF1.0 and GOMF1.0.obj are shareware products which are to be utilized
  only by those who pay the suggested sum of $5.00 each for the use of either
  program.  If you find this software useful, please remit this minimal sum
  to the address below.

  GOMF1.0 is not public domain software. Therefore, neither GOMF1.0 nor
  GOMF1.0.obj may be included with any other program released, whether public
  domain or commercial without the prior, written consent of the author,
  Christian Johnsen.  If you wish to do so please arrange this by writing me
  at the following address with the particulars.  I'll entertain customizing
  this system for your particular application's use if required.

  I wish to mention, at this point, that I hope no one is offended by the
  icon I've designed for these programs.  No disrespect was intended.


  Contents
  ~~~~~~~~

  The disk on which you found this information file should contain the
  following programs and text files plus their attendant icons.

  1.  GOMFinfo - this text file of instructions and terms.

  2.  GOMF1.0 - the global error handler.

  3.  GOMF1.0.obj - the error handler object code link module.

  4.  Hey! - a program to allow recall of GOMF1.0 for user discretionary
      operations on the program display.

  5.  Err1 - a simple Workbench screen error test program.

  6.  Err2 - an error test program with a custom double length screen,
      containing fourteen windows.

  7.  Err3 - a custom double length screen error test program containing
      no windows.

  8.  Err4 - an example test program linked with GOMF1.0.obj to demonstrate
      the capabilities of the link module.

  9.  Err4.asm - the source code for Err4 that demonstrates the use of the
      link module GOMF1.0.obj.

  Instructions
  ~~~~~~~~~~~~

  GOMF1.0 is the global system error handler which I designed for the
  average Amigaiod.  It notifies the user that it has installed itself, then
  snoozes until the system scrams.  Then, according to user selection, it
  restores the system in one of four ways.  The other version of the program,
  GOMF1.0.obj, was designed for programmers.  It must be linked to a program
  after assembly or compilation.  It will handle errors similar to GOMF1.0,
  except that it can be customized as described in 'Using GOMF1.0.obj'.  The
  Hey! program is useful if it becomes necessary to reenter the error handler
  because you have exited it prematurely.  The Err1, Err2, and Err4 programs
  are provided so that you may test the operation of GOMF1.0 and familiarize
  yourself with its operation before you attempt to beat the guru under
  normal operation conditions.  Err4 is a demo of a program linked to
  GOMF1.0.obj.


  Using GOMF1.0
  ~~~~~~~~~~~~~

  This program can be run either from the CLI or the Workbench.  To use the
  program from the CLI enter...

  Run GOMF1.0

  I suggest that the program be kept in the C directory of the Workbench
  disk, and the above line be added to your startup-sequence.  This way your
  Amiga system will be made reasonably crash proof upon booting up.

  When run there will be a momentary window displayed informing you that
  GOMF1.0 is activated.  It will detect any setup errors and report these, if
  found, so that you'll know that the system is then not protected.  GOMF1.0
  and GOMF1.0.obj examine system structures to determine which of either
  68000, 68010 or 68020 microprocessors are on board and configures itself to
  handle the appropriate supervisor stack frame.  I have not, at this time
  (June 25, 1987), had the pleasure of testing this on either the 68010 or
  68020 configured machines.  I would appreciate any feedback on the success
  or failure of GOMF1.0 on either of these processors.

  Once an error is encountered, the normal system requester, giving the RETRY
  or CANCEL options will be presented.  Select the CANCEL gadget.  The
  SYSTEM SCRAMMED window will then be presented.  It contains useful
  information, similar to that encoded into the guru meditation alert number,
  but it is decoded and presented in English text.  This includes the alert
  number, the program counter address of the instruction immediately
  following the error, the library or vector type of the error, the general
  type of problem and a description of a more specific nature.  This includes
  all known error types listed in the developer's alerts include file.  There
  are also four gadget options.  You must use caution when using any of this
  tool's options.

  The GOMF gadget removes, as safely as possible, the errant program, then
  returns the system to normal processing.  It will not fix the problem in
  the program, only remove the task or process without the need to reset the
  computer.  Whenever the GOMF gadget is tweaked, the results of the
  operation are displayed.  This would be either the completed message, if
  successful, or an error message in the event of a failure.  Normally it is
  only the removal of the display elements of a program which yield errors.
  You can usually use the WHAP gadget as suggested in the error message to
  recover the display should this occur, before attempting to use GOMF a
  second time.  The messages provided by the error handler should be
  sufficient to guide you through the removal of a program, but please use
  the Err1, Err2 and Err4 programs to practice operations.

  The WHAP gadget is provided for use when a program's windows or screen
  elude the automatic scan features of GOMF.  For instance, if it is
  ascertained that only the WB screen is active, then you will be requested
  to click on the WHAP gadget followed by the offensive program's window or
  screen.  WHAP will remove the display element selected.  WHAP will make it
  possible to remove piece by piece a multi-screen and/or multi-window
  display, if necessary.  You will have to either, use the Left-AMIGA and N
  or Left-AMIGA M key combinations to flip between the Workbench and the
  applications' screen if it uses one of its own, or pull down the Workbench
  screen to expose the faulty programs' display, when using this option.

  The RESET gadget allows a reboot of the system without visiting the guru
  or giving the Amiga three finger salute.

  The GURU gadget calls the normal system alert as usual.


  Using GOMF1.0.obj
  ~~~~~~~~~~~~~~~~~

  GOMF1.0.obj is an object code file generated by an assembler.  For a
  programmer to use it the code must be linked to the object output of an
  assembler or compiler.  The ALINK linker directives FROM or ROOT are used
  to accomplish this.  For example...

  ALINK MyProg,GOMF1.0.obj to ProgName

  GOMF1.0.obj provides the same protection as GOMF1.0, however the linked
  module allows the programmer to design his or her own method of handling
  these error returns.

  Setting up your source code for use with GOMF1.0.obj is relatively easy.
  Your code must make references to the following external labels, _GOMF
  and _GOMFEnding.  You may also wish to utilize other information with
  external reference labels of _WHAP, _ProgramCounter, _GeneralErr,
  _LibraryErr, _SpecificErr.  GOMF1.0.obj requires your source define its
  own external label, _ErrorHandler, which is coded to recieve the return to
  normal processing, after the error has been neutralized.  You will have to
  write up a custom routine called _ErrorHandler that will recieve the
  program flow after an error has been detected elsewhere in the program.
  This may be simply closing screens, windows and libraries before exiting,
  or you may wish to analyse the situation more completely and continue
  execution of your program code at another point.  The potential of this
  feature is not small.

  Early on in your program do a simple call of _GOMF such as JSR _GOMF or
  GOMF().  This will activate the features of the linked module.  Before
  your program cleans up and ends you must call _GOMFEnding in a like
  fashion so that _GOMF can release its memory useage etc.

  To recap, _GOMF is the initialization entry point.  _GOMFEnding is the
  termination entry point.  The other labels available are a structure laid
  out as follows...

  STRUCTURE  GOMF1.0,0
  ULONG      _ProgramCounter  value of the program counter after the error
  APTR       _LibraryErr      pointer to null terminated string discriptor
  APTR       _GeneralErr      pointer to null terminated string discriptor
  APTR       _SpecificErr     pointer to null terminated string discriptor
  UBYTE      _WHAP            boolean TRUE or FALSE of WHAP gadget selction

  See the source code example of the use of this structure in Err4.asm for
  more clarification.

  Credits
  ~~~~~~~

  GOMF1.0, GOMF1.0.obj, Err1, Err2, Err3, Err4, and Hey! were written
  entirely in assembly language by Christian Johnsen.

  I trust this application is of use and value to you, and I welcome any
  communication via mail at this address.



                               Christian Johnsen

                              3169  Consort Court

                                   Clearbrook

                                British Columbia

                                    Canada

                                   V2T  4J5

                                [phone]